<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>lua-resty-jit-uuid documentation</title>
    <link rel="stylesheet" href="ldoc_pale.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>lua-resty-jit-uuid</h1>


<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
</ul>


<h2>Modules</h2>
<ul class="nowrap">
  <li><strong>jit-uuid</strong></li>
</ul>

</div>

<div id="content">

<h1>Module <code>jit-uuid</code></h1>
<p>jit-uuid
 Fast and dependency-free UUID library for LuaJIT/ngx_lua.</p>
<p>

</p>
    <h3>Info:</h3>
    <ul>
        <li><strong>Release</strong>: 0.0.7</li>
        <li><strong>License</strong>: MIT</li>
        <li><strong>Author</strong>: Thibault Charbonnier</li>
    </ul>


<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#seed">seed (seed)</a></td>
	<td class="summary">Seed the random number generator.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#is_valid">is_valid (str)</a></td>
	<td class="summary">Validate a string as a UUID.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#generate_v4">generate_v4 ()</a></td>
	<td class="summary">Generate a v4 UUID.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#factory_v3">factory_v3 (namespace)</a></td>
	<td class="summary">Instanciate a v3 UUID factory.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#factory_v5">factory_v5 (namespace)</a></td>
	<td class="summary">Instanciate a v5 UUID factory.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#generate_v3">generate_v3 (namespace, name)</a></td>
	<td class="summary">Generate a v3 UUID.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#generate_v5">generate_v5 (namespace, name)</a></td>
	<td class="summary">Generate a v5 UUID.</td>
	</tr>
</table>

<br/>
<br/>


    <h2 class="section-header "><a name="Functions"></a>Functions</h2>

    <dl class="function">
    <dt>
    <a name = "seed"></a>
    <strong>seed (seed)</strong>
    </dt>
    <dd>
    Seed the random number generator.
 Under the hood, this function calls <a href="https://www.lua.org/manual/5.1/manual.html#pdf-math.randomseed">math.randomseed</a>.
 It makes sure to use the most appropriate seeding technique for
 the current environment, guaranteeing a unique seed.</p>

<p> To guarantee unique UUIDs, you must have correctly seeded
 the Lua pseudo-random generator (with <a href="https://www.lua.org/manual/5.1/manual.html#pdf-math.randomseed">math.randomseed</a>).
 You are free to seed it any way you want, but this function
 can do it for you if you'd like, with some added guarantees.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">seed</span>
            <span class="types"><span class="type">number</span></span>
         (Optional) A seed to use. If none given, will
 generate one trying to use the most appropriate technique.
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

           <span class="types"><span class="type">number</span></span>
        <a href="index.html#seed">seed</a>: the seed given to <a href="https://www.lua.org/manual/5.1/manual.html#pdf-math.randomseed">math.randomseed</a>.
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span> <span class="string">'resty.jit-uuid'</span>
uuid.seed()

<span class="comment">-- in ngx_lua, seed in the init_worker context:
</span>init_worker_by_lua {
  <span class="keyword">local</span> uuid = <span class="global">require</span> <span class="string">'resty.jit-uuid'</span>
  uuid.seed()
}</pre>
    </ul>

</dd>
    <dt>
    <a name = "is_valid"></a>
    <strong>is_valid (str)</strong>
    </dt>
    <dd>
    Validate a string as a UUID.
 To be considered valid, a UUID must be given in its canonical
 form (hexadecimal digits including the hyphen characters).
 This function validates UUIDs disregarding their generation algorithm,
 and in a case-insensitive manner, but checks the variant field.</p>

<p> Use JIT PCRE if available in OpenResty or fallbacks on Lua patterns.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">str</span>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
         String to verify.
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

           <span class="types"><span class="type">boolean</span></span>
        <code>valid</code>: true if valid UUID, false otherwise.
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span> <span class="string">'resty.jit-uuid'</span>

uuid.is_valid <span class="string">'cbb297c0-a956-486d-ad1d-f9bZZZZZZZZZ'</span> <span class="comment">--&gt; false
</span>uuid.is_valid <span class="string">'cbb297c0-a956-486d-dd1d-f9b42df9465a'</span> <span class="comment">--&gt; false (invalid variant)
</span>uuid.is_valid <span class="string">'cbb297c0a956486dad1df9b42df9465a'</span>     <span class="comment">--&gt; false (no dashes)
</span>uuid.is_valid <span class="string">'cbb297c0-a956-486d-ad1d-f9b42df9465a'</span> <span class="comment">--&gt; true</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "generate_v4"></a>
    <strong>generate_v4 ()</strong>
    </dt>
    <dd>
    Generate a v4 UUID.
 v4 UUIDs are created from randomly generated numbers.



    <h3>Returns:</h3>
    <ol>

           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        <code>uuid</code>: a v4 (randomly generated) UUID.
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span> <span class="string">'resty.jit-uuid'</span>

<span class="keyword">local</span> u1 = uuid()             <span class="comment">---&gt; __call metamethod
</span><span class="keyword">local</span> u2 = uuid.generate_v4()</pre>
    </ul>

</dd>
    <dt>
    <a name = "factory_v3"></a>
    <strong>factory_v3 (namespace)</strong>
    </dt>
    <dd>
    Instanciate a v3 UUID factory.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">namespace</span>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
         (must be a valid UUID according to <a href="index.html#is_valid">is_valid</a>)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>
        <li>
           <span class="types"><span class="type">function</span></span>
        <code>factory</code>: a v3 UUID generator.</li>
        <li>
           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        <code>err</code>: a string describing an error</li>
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span> <span class="string">'resty.jit-uuid'</span>

<span class="keyword">local</span> fact = <span class="global">assert</span>(uuid.factory_v3(<span class="string">'e6ebd542-06ae-11e6-8e82-bba81706b27d'</span>))

<span class="keyword">local</span> u1 = fact(<span class="string">'hello'</span>)
<span class="comment">---&gt; 3db7a435-8c56-359d-a563-1b69e6802c78
</span>
<span class="keyword">local</span> u2 = fact(<span class="string">'foobar'</span>)
<span class="comment">---&gt; e8d3eeba-7723-3b72-bbc5-8f598afa6773</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "factory_v5"></a>
    <strong>factory_v5 (namespace)</strong>
    </dt>
    <dd>
    Instanciate a v5 UUID factory.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">namespace</span>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
         (must be a valid UUID according to <a href="index.html#is_valid">is_valid</a>)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>
        <li>
           <span class="types"><span class="type">function</span></span>
        <code>factory</code>: a v5 UUID generator.</li>
        <li>
           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        <code>err</code>: a string describing an error</li>
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span> <span class="string">'resty.jit-uuid'</span>

<span class="keyword">local</span> fact = <span class="global">assert</span>(uuid.factory_v5(<span class="string">'e6ebd542-06ae-11e6-8e82-bba81706b27d'</span>))

<span class="keyword">local</span> u1 = fact(<span class="string">'hello'</span>)
<span class="comment">---&gt; 4850816f-1658-5890-8bfd-1ed14251f1f0
</span>
<span class="keyword">local</span> u2 = fact(<span class="string">'foobar'</span>)
<span class="comment">---&gt; c9be99fc-326b-5066-bdba-dcd31a6d01ab</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "generate_v3"></a>
    <strong>generate_v3 (namespace, name)</strong>
    </dt>
    <dd>
    Generate a v3 UUID.
 v3 UUIDs are created from a namespace and a name (a UUID and a string).
 The same name and namespace result in the same UUID. The same name and
 different namespaces result in different UUIDs, and vice-versa.
 The resulting UUID is derived using MD5 hashing.</p>

<p> This is a sugar function which instanciates a short-lived v3 UUID factory.
 It is an expensive operation, and intensive generation using the same
 namespaces should prefer allocating their own long-lived factory with
 <a href="index.html#factory_v3">factory_v3</a>.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">namespace</span>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
         (must be a valid UUID according to <a href="index.html#is_valid">is_valid</a>)
        </li>
        <li><span class="parameter">name</span>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>



        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>
        <li>
           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        <code>uuid</code>: a v3 (namespaced) UUID.</li>
        <li>
           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        <code>err</code>: a string describing an error</li>
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span> <span class="string">'resty.jit-uuid'</span>

<span class="keyword">local</span> u = uuid.generate_v3(<span class="string">'e6ebd542-06ae-11e6-8e82-bba81706b27d'</span>, <span class="string">'hello'</span>)
<span class="comment">---&gt; 3db7a435-8c56-359d-a563-1b69e6802c78</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "generate_v5"></a>
    <strong>generate_v5 (namespace, name)</strong>
    </dt>
    <dd>
    Generate a v5 UUID.
 v5 UUIDs are created from a namespace and a name (a UUID and a string).
 The same name and namespace result in the same UUID. The same name and
 different namespaces result in different UUIDs, and vice-versa.
 The resulting UUID is derived using SHA-1 hashing.</p>

<p> This is a sugar function which instanciates a short-lived v5 UUID factory.
 It is an expensive operation, and intensive generation using the same
 namespaces should prefer allocating their own long-lived factory with
 <a href="index.html#factory_v5">factory_v5</a>.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">namespace</span>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
         (must be a valid UUID according to <a href="index.html#is_valid">is_valid</a>)
        </li>
        <li><span class="parameter">name</span>
            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>



        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>
        <li>
           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        <code>uuid</code>: a v5 (namespaced) UUID.</li>
        <li>
           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
        <code>err</code>: a string describing an error</li>
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> uuid = <span class="global">require</span> <span class="string">'resty.jit-uuid'</span>

<span class="keyword">local</span> u = uuid.generate_v5(<span class="string">'e6ebd542-06ae-11e6-8e82-bba81706b27d'</span>, <span class="string">'hello'</span>)
<span class="comment">---&gt; 4850816f-1658-5890-8bfd-1ed14251f1f0</span></pre>
    </ul>

</dd>
</dl>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2017-12-16 15:37:21 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
